﻿%YAML 1.2
--- 
Title:          YAML 1.2 problems/fixes with specification examples 

Based on:       http://yaml.org/spec/1.2/spec.html (3rd Edition, Patched at 2009-10-01)

Author:         Burt Harris

Last change:    2009-12-09 13:41 PST

Summary:        The new YAML 1.2 specification is great.   I've been using the 
                examples as part of my unit testing, and discovered a few
                small corrections I believe should be made.   These all seem 
                to be typos rather than any sort of change in the meaning of 
                the spec.

Example 5.11:   Examples differ in two places by letter case on word "Line".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!str "Line break (no glyph)\n\
                          Line break (glyphed)\n"

Example 5.12:   For consistency, right hand side needs two !!str tags.

                I propose changing the right hand side to read:

                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "quoted"
                      : !!str "Quoted \t",
                      ? !!str "block"
                      : !!str "void main() {\n\
                        \tprintf(\"Hello, world!\\n\");\n\
                        }\n",
                    }

                
Example 6.21:   Block version is missing a required end-of-document indicator.

                I propose changing the _left_ hand side to read:
                
                    %TAG !m! !my-
                    --- # Type here
                    !m!light fluorescent
                    ...
                    %TAG !m! !my-
                    --- # Color here
                    !m!light green
                
Example 6.22:   Flow version isn't a sequence, doesn't match block version.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                        !<tag:example.com,2000:app/foo> "bar"
                        ]

Example 6.23:   Perhaps it's intended to prove a point, but there
                seem to be gratuitous differences between left and 
                right hand version of this (e.g. number of anchors.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ?  !!str &B1 "foo"
                      :  !!str "bar",
                      ?  !!str &B2 "baz"
                      :  *B1,
                    }

Example 7.1:    Map entries unnecessarily out-of-order (confusing.)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "First occurrence"
                      : &A !!str "Foo",
                      ? !!str "Second occurrence"
                      : *A,
                      ? !!str "Override anchor"
                      : &B !!str "Bar",
                      ? !!str "Reuse anchor"
                      : *B,
                    }

Example 7.10:   Extra comma in "Up, up, and away".
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "::vector",
                      !!str ": - ()",
                      !!str "Up, up, and away!",
                      !!int "-123",
                      !!str "http://example.com/foo#bar",
                      !!seq [
                        !!str "::vector",
                        !!str ": - ()",
                        !!str "Up, up and away!",
                        !!int "-123",
                        !!str "http://example.com/foo#bar",
                      ],
                    ]

Example 8.2:    Should newline after tab be preserved rather than folded?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!str "detected\n",
                      !!str "\n\n# detected\n",
                      !!str " explicit\n",
                      !!str "\t\ndetected\n",
                    ]
                                    

Example 8.5:    Block version contains a double-down-arrow glyph, no longer a break 1.2.
                I propose changing the left hand side to read:
                
                    ·# Strip↓
                    ··# Comments:↓
                    strip: |-↓
                    ··# text↓
                    ··↓
                    ·# Clip↓
                    ··# comments:↓
                    ↓
                    clip: |↓
                    ··# text↓
                    ·↓
                    ·# Keep↓
                    ··# comments:↓
                    ↓
                    keep: |+↓
                    ··# text↓
                    ↓
                    ·# Trail↓
                    ··# comments.↓
                
                Should the last scalar in the flow version have two newlines?
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "strip"
                      : !!str "# text",
                      ? !!str "clip"
                      : !!str "# text\n",
                      ? !!str "keep"
                      : !!str "# text\n\n",
                    }
                    
                    

Example 8.10-8.13 :   Flow version is missing trailing backslash on first bullet line.
                The Block version of 8.12 & 8.13 is missing a final 's' on the final bulleted line
                
                I propose changing the left hand side on 8.12 & 8.13 to match 8.10, like this:
                    >

                     folded
                     line

                     next
                     line
                       * bullet

                       * list
                       * lines

                     last
                     line

                    # Comment                

                I propose changing the right hand side of all four to read:
                    %YAML 1.2
                    ---
                    !!str "\n\
                          folded line\n\
                          next line\n\
                          \  * bullet\n\
                          \n\
                          \  * list\n\
                          \  * lines\n\
                          \n\
                          last line\n"


Example 8.15:   Flow version missing a comma in inner sequence.
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!null "",
                      !!str "block node\n",
                      !!seq [
                        !!str "one",
                        !!str "two",
                      ],
                      !!map {
                        ? !!str "one"
                        : !!str "two",
                      },
                    ]
                    
Example 8.19:   Flow version has an extra comma on line 11.   In my parser, 
                this generates an extra unexpected !!null : !!null mapping
                entry at that point in the parse (is that right?!?)
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!seq [
                      !!map {
                         !!str "sun" : !!str "yellow",
                      },
                      !!map {
                        ? !!map {
                          ? !!str "earth"
                          : !!str "blue"
                        }
                        : !!map {
                          ? !!str "moon"
                          : !!str "white"
                        },
                      }
                    ]

Example 8.21:   Flow version of folded and literal missing normalized newlines.   
                
                I propose changing the right hand side to read:
                    %YAML 1.2
                    ---
                    !!map {
                      ? !!str "literal"
                      : !!str "value\n",
                      ? !!str "folded"
                      : !<!foo> "value\n",
                    }                                    
                    
Example 9.3:    Block version - Comments not permitted in literals.

                I propose changing the _left_ hand side to read:
                
                    Bare
                    document
                    ...
                    # No document
                    ...
                    |
                    %!PS-Adobe-2.0
                    ...  #Looked like a directive, but the first line

                Flow version - Missing end-of-document indicator before 
                2nd YAML directive.   
                
                I propose changing the right  hand side to read:

                    %YAML 1.2
                    ---
                    !!str "Bare document"
                    ...
                    %YAML 1.2
                    ---
                    !!str "%!PS-Adobe-2.0\n"
                
                

Example 9.5:    Missing space in second YAML directive.
                
                I propose changing the _left_ hand side to read:
                    %YAML 1.2
                    --- |
                    %!PS-Adobe-2.0
                    ...
                    %YAML 1.2
                    ---
                    # Empty
                    ...
                
---  # YAML 1.1 # Old Specification issues: may be out of date
Example 9.1:   Trailing brace needs to be indented.
Example 9.7:   Trailing brace needs to be indented.
Example 9.12:  Output has extra second commas in "Up, up, and away"
Example 9.13:  Trailing brace needs to be indented.
Example 9.15:  How are content that looks like document indicators made safe?
Example 9.20:  Why doesn't tab (leading whitespace) counting a spaced line, 
               preserve the newline after it?
Example 9.23:  Shouldn't the PS in the "strip:" literal be reflected on output?
               Looks like it's been removed in 1.2 nearly identical example 8.5.
Example 10.7:  Does the empty key line needs a comma?
Example 10.7:  Does the line starting with "simple key" needs a comma?
